---
title: Toaster
description: A comprehensive toast notification system with multiple variants, actions, and customizable behavior for displaying user feedback.
---
import { BasicToast, ToastVariants, ToastWithDescription, ToastWithActions, ToastWithCustomDuration, ToastWithPromise } from "./toaster.example";

## Overview

The Toaster component provides a comprehensive toast notification system for displaying user feedback throughout your application. It's designed to show temporary messages with multiple variants, actions, and customizable behavior.

## Usage

```tsx
import { toast } from "@unkey/ui";

export default function MyComponent() {
  const showToast = () => {
    toast({
      title: "Success!",
      description: "Your action was completed successfully.",
      variant: "success",
    });
  };

  return <Button onClick={showToast}>Show Toast</Button>;
}
```

## Examples

### Basic Toast
Simple toast notification with title and default styling.

<BasicToast />

### Toast Variants
Different visual styles for various message types.

<ToastVariants />

### Toast with Description
Toast with additional descriptive text for more context.

<ToastWithDescription />

### Toast with Actions
Interactive toast with action buttons for user engagement.

<ToastWithActions />

### Custom Duration
Toast with custom display duration and timing control.

<ToastWithCustomDuration />

### Promise-based Toast

Toast that updates based on promise resolution status.

<ToastWithPromise />

## Features

- **Multiple Variants**: Different visual styles (default, success, error, warning)
- **Rich Content**: Support for titles, descriptions, and actions
- **Customizable Duration**: Configurable display timing
- **Promise Integration**: Built-in support for promise-based toasts
- **Accessibility**: Full accessibility support with proper ARIA attributes
- **Responsive Design**: Adapts to different screen sizes
- **Dark Mode Support**: Consistent appearance in light and dark themes
- **Action Buttons**: Interactive buttons within toast notifications

## Props

### Toast Function
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | - | The main title text of the toast |
| `description` | `string` | - | Optional description text |
| `variant` | `"default" \| "success" \| "error" \| "warning"` | `"default"` | The visual variant of the toast |
| `duration` | `number` | `5000` | Duration in milliseconds before auto-dismiss |
| `action` | `ToastActionElement` | - | Optional action button |
| `className` | `string` | - | Additional CSS classes |

### ToastActionElement
| Prop | Type | Description |
|------|------|-------------|
| `altText` | `string` | Accessible text for the action |
| `children` | `React.ReactNode` | Action button content |

## Variants

### Default
- Neutral gray styling
- General information messages
- Standard duration and behavior

### Success
- Green styling for positive feedback
- Successful operations and confirmations
- Encourages positive user experience

### Error
- Red styling for error messages
- Failed operations and critical issues
- Requires user attention

### Warning
- Yellow/orange styling for warnings
- Cautionary messages and alerts
- Important but not critical information

## Structure

The Toaster system is composed of several parts:

1. **Toaster Provider** - Context provider for toast management
2. **Toast Function** - API for creating and displaying toasts
3. **Toast Component** - Individual toast notification
4. **Toast Container** - Container for managing multiple toasts

## Styling

The Toaster component includes default styling with:

- Consistent spacing and typography
- Color-coded variants for semantic meaning
- Smooth animations for enter/exit
- Dark mode support
- Responsive design
- Focus states for accessibility

### Custom Styling

You can customize the appearance using className props:

```tsx
toast({
  title: "Custom Toast",
  className: "custom-toast-class",
  action: {
    altText: "Custom action",
    children: <Button className="custom-action-class">Action</Button>
  }
});
```

## Accessibility

The Toaster component is built with accessibility in mind:

- **ARIA Attributes**: Proper ARIA labels and live regions
- **Screen Reader Support**: Announces toast content appropriately
- **Focus Management**: Maintains focus context during toast display
- **High Contrast**: Maintains proper contrast ratios
- **Keyboard Navigation**: Full keyboard support for actions
- **Dismissible**: Multiple ways to dismiss toasts